TGEA 1.7 Porting Guide

Introduction

The goal of this guide is to provide a launching point for people just starting out using TGEA 1.7, with detailed help for those moving from TGEA 1.0.3 and TGE 1.5.2.

 

The High Level Directory Explanation will provide you with a brief description of how standard TGEA 1.7 projects (such as the ones found in GameExamples) are laid out.  Structuring your project directory similar to this is recommended, but not an absolute requirement.

 

The actual porting guide is broken into 2 sections: Summary of Changes and Checklist. 

 

The Changes Summary is a reference of critical code changes you should keep in mind, or use to modify your existing projects that were created pre-1.7. 

 

The Checklist is a simple set of steps to follow when performing a high level transfer of your pre-1.7 projects.


For more detailed information on setting up your system for Torque development, head over to the Getting Started section of the documents.

 

High Level Directory Explanation
The TGEA 1.7 codebase is a unification of the TGE and TGEA codebases.  The core of the engine is based on part new code and part stable TGE/TGEA code.  The rendering engine is based on TGEA, with an updated GFX to support d3d, “shaderized”, and fixed function rendering.  The windowing code allows multiple windows, ideal for tool development. 

One of the major changes in TGEA 1.7 compared to TGE/TGEA is the project layout.  Whereas before the engine was a game and one created a new game by modifying the single SDK project, we now are set up to support multiple projects side by side, each treating the engine as a library.  To this end, you'll find several projects in the GameExamples directory.  Each of these is laid out the same:

GameExamples/
      T3DDemo/

 

*Note that project directories need to be 2 deep in the TGEA directory just like above in order for the project generator to work correctly.

For more details on folder hierarchy and what projects ship with TGEA 1.7, check out the Directory Layout section of the Getting Started Docs.

Porting from TGE/TGEA


Summary of changes before porting from TGE/TGEA (use for reference only, a checklist for porting is provided below)

General Changes:

Rendering/GFX Changes:

General Engine Changes:

General Script Changes:

Particle Emitter Changes:

Console and Sim Changes:

SFX/Audio Changes:
      ConsoleFunction(sfxStop, void, 2, 2, "(S32 id): stop a source, equivalent to id.stop()")

      {

         S32 id = dAtoi(argv[1]);


         SFXSource * obj;


         if (Sim::findObject<SFXSource>(id, obj))

            obj->stop();

      }


      SFXDescription::initPersistFields::addField("type", TypeS32, Offset(mChannel, SFXDescription)); // for backwards compatibility


Merging:



Common Porting/Upgrade Checklist (TGE or TGEA)

Prep:
If you wish to start with a completely clean TGEA 1.7.1 project and add your code to it, try using the new project generator tool included with the latest version.

For detailed information on how to use the new tool, read through the New Project Generator Guide.


SOURCE CHANGES:

Extract all of your custom files from your original project, and place them in the top level <MyGame>/source directory. You should not need to change any #include lines, as all directory references are abstracted.

If you have made changes directly to stock code (Player.cpp for example), you will have to manually merge your changes.

Once you have finished separating your changes, execute the "generateProjects.bat" file at the top level of your project directory. This will automatically generate .vsproj project files and a new solution file.

SCRIPT CHANGES:

delete template versions of /client, /data, /server if desired

Important Note: the /common directory is still important at this stage, and we are using it as a "wrapper" to ease the porting process.
If you have for whatever reason removed the use of the /common directory, you will need to manually merge and adjust the calls and scripts in
the various directories. The /clientScripts/client.cs is of particular importance.

copy over your /client, /data, and /server directories, as well as your main.cs from your project to /scriptsAndAssets.

/client/init.cs:

add $Pref::Video::MainWindowTitle = "Torque Game Engine Advanced"; Under the

   $Client::MissionTypeQuery = "Any";

add    loadMaterials(); after

   // Default player key bindings
   exec("./scripts/default.bind.cs");
   exec("./config.cs");



in scriptsAndAssets/main.cs add in

// Start up the audio system.
   sfxStartup();

after

   // Load the scripts that start it all...
   exec("./client/init.cs");
   exec("./server/init.cs");

Re-export all of your interiors with TGE_A 1.03 map2dif
--alternatively, you can use Constructor 1.03, using the "Save as DIF" option

if you have a hard coded mission file, make sure your createServer line properly expands file names:

createServer("SinglePlayer", expandFileName("~/data/missions/features.mis"));

If you have a custom mission loading mechanism, you will need to make sure you are properly
tracking the directory structure changes

Copy in the new waterblock from the TGEDemo (use as template) into your .mis file(s)

Change all references:

AudioDescription to SFXDescription
AudioProfile to SFXProfile
alxPlay/alxStop to sfxPlay/sfxStop

TGEA 1.7 is more stringent when it comes to namespace management, and will not like if you name an object the same as it's underlying class, such as:

new Sun(Sun)

You should add the word "Object" after the token that is the same for any objects created in your mission file (or elsewhere):

new Sun(SunObject)

new MissionArea(MissionAreaObject)

etc.

TGEA 1.7 will also warn if you have a persistent field class or superClass that defines a namespace that already exists for this object.




PORTING FROM TGEA 1.0.3 or TGE 1.5.2:

--comment out all 4 legacy terrain shader defs in scriptsAndAssets/client/scripts/shaders.cs to read:

/*
new ShaderData( TerrShader )
{
   DXVertexShaderFile   = "shaders/legacyTerrain/terrainLightingV.hlsl";
   DXPixelShaderFile    = "shaders/legacyTerrain/terrainLightingP.hlsl";
   pixVersion = 1.1;
};

new ShaderData( TerrBlender20Shader )
{
   DXVertexShaderFile     = "shaders/legacyTerrain/terrainBlenderPS20V.hlsl";
   DXPixelShaderFile      = "shaders/legacyTerrain/terrainBlenderPS20P.hlsl";
   pixVersion = 2.0;
};

new ShaderData( TerrBlender11AShader )
{
   DXVertexShaderFile     = "shaders/legacyTerrain/terrainBlenderPS11AV.hlsl";
   DXPixelShaderFile      = "shaders/legacyTerrain/terrainBlenderPS11AP.hlsl";
   pixVersion = 1.1;
};

new ShaderData( TerrBlender11BShader )
{
   DXVertexShaderFile     = "shaders/legacyTerrain/terrainBlenderPS11BV.hlsl";
   DXPixelShaderFile      = "shaders/legacyTerrain/terrainBlenderPS11BP.hlsl";
   pixVersion = 1.1;
};

*/





© GarageGames.com Home Back to Top